Security News
Cloudflare Adds Security.txt Setup Wizard
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
keen-analysis
Advanced tools
Install this package from NPM Recommended
$ npm install keen-analysis --save
Or load it from public CDN:
<script src="https://cdn.jsdelivr.net/npm/keen-analysis@2"></script>
Login to Keen IO to create a project and grab the Project ID and Read Key from your project's Access page.
The following examples demonstrate how to get up and running quickly with our Compute API. This SDK can also contains basic HTTP wrappers that can be used to interact with every part of our platform.
If any of this is confusing, that's our fault and we would love to help. Join our Slack community or send us a message.
Looking for tracking capabilities? Check out keen-tracking.js.
Upgrading from an earlier version of keen-js? Read this.
Create a new client
instance with your Project ID and Read Key, and use the .query()
method to execute an ad-hoc query. This client instance is the core of the library and will be required for all API-related functionality.
// browser/front-end
import Keen from 'keen-analysis';
// for Node.js/back-end
// const Keen = require('keen-analysis');
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
client
.query('count', {
event_collection: 'pageviews',
timeframe: 'this_14_days'
})
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
Important: the res
response object returned in the example above will also include a query
object containing the analysis_type
and query parameters shaping the request. This query information is artificially appended to the response by this SDK, as this information is currently only provided by the API for saved queries. Why? Query parameters are extremely useful for intelligent response handling downstream, particularly by our own automagical visualization capabilities in keen-dataviz.js.
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
client
.query('saved', 'pageviews-this-14-days')
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
Note the special param name
to specify the name of the cached dataset that you have already created.
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
client
.query('dataset', {
name: 'my-cached-dataset',
index_by: 'customer.id',
timeframe: 'this_7_days'
})
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
The following HTTP methods are exposed on the client instance:
.get(string)
.post(string)
.put(string)
.del(string)
These HTTP methods take a URL (string) as a single argument and return an internal request object with several methods that configure and execute the request, finally returning a promise for the asynchronous response. These methods include:
.auth(string)
: sets the API_KEY as an Authorization header.headers(object)
: sets headers to apply to the request.send()
: handles an optional object of parameters, executes the request and returns a promise.abort()
: cancels already running requestThe following example demonstrates the full HTTP request that is executed when client.query()
is called (detailed above):
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
client
.post(`https://api.keen.io/3.0/projects/${client.projectId()}/queries/count`)
.auth(client.readKey())
.send({
event_collection: 'pageviews',
timeframe: 'this_14_days'
})
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
As an added convenience, API URLs can be generated using the client.url()
.
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
masterKey: 'YOUR_MASTER_KEY'
});
// Retrieve all saved queries
client
.get(client.url('queries', 'saved'))
.auth(client.masterKey())
.send()
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
const query = client
.get(client.url('queries', 'saved'))
.auth(client.masterKey())
.send();
// cancel
query.abort();
/*
query.then(res => {
console.log(res);
})
.catch(err => {
console.log(err);
});
*/
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
// Get average
client
.post(client.url('queries', 'average'))
.auth(client.readKey())
.send({
event_collection: 'purchases',
target_property: 'price',
timeframe: 'this_27_days'
})
.then(res => {
console.log(res);
// Handle results
})
.catch(err => {
console.log(err);
// Handle errors
});
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
masterKey: 'YOUR_MASTER_KEY'
});
// Update a saved query
client
.put(client.url('queries', 'saved', 'daily-pageviews-this-14-days'))
.auth(client.masterKey())
.send({
refresh_rate: 60 * 60 * 4,
query: {
analysis_type: 'count',
event_collection: 'pageviews',
timeframe: 'this_14_days'
},
metadata: {
display_name: 'Daily pageviews (this 14 days)'
}
// ...
})
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
masterKey: 'YOUR_MASTER_KEY'
});
// Delete a saved query
client
.del(client.url('queries', 'saved', 'new-saved-query'))
.auth(client.masterKey())
.send()
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
The Keen.Query
object and client.run()
method introduced in keen-js are still supported. However, client.run()
now also returns a promise, as an alternate interface to the node-style callback.
import Keen from 'keen-analysis';
const client = new Keen({
projectId: 'YOUR_PROJECT_ID',
readKey: 'YOUR_READ_KEY'
});
const query = new Keen.Query('count', {
event_collection: 'pageviews',
timeframe: 'this_14_days'
});
// Node-style callback
client.run(query, (err, res) =>{
if (err) {
// Handle errors
}
else {
// Handle results
}
});
// promise
client
.run(query)
.then(res => {
// Handle results
})
.catch(err => {
// Handle errors
});
There are several breaking changes from earlier versions of keen-js.
.get()
, .post()
, .put()
, and .del()
) for interacting with various API resources. The new Promise-backed design of this SDK necessitated a full rethinking of how these methods behave.Keen.Query
object in camelCase format, and would be converted to the underscore format that the API requires. Eg: eventCollection
would be converted to event_collection
before being sent to the API. This pattern has caused plenty of confusion, so we have axed this conversion entirely. All query parameters must be supplied in the format outlined by the API reference (event_collection
).Keen.Request
object has been removed: this object is no longer necessary for managing query requests.client.url()
: This method previously included https://api.keen.io/3.0/projects/PROJECT_ID
plus a path
argument ('/events/whatever'). This design severely limited its utility, so we've revamped this method.This method now references an internal collection of resource paths, and constructs URLs using client configuration properties like host
and projectId
:
const url = client.url('projectId');
// Renders {protocol}://{host}/3.0/projects/{projectId}
// Returns https://api.keen.io/3.0/projects/PROJECT_ID
Default resources:
{protocol}
://{host}
',{protocol}
://{host}
/3.0',{protocol}
://{host}
/3.0/projects',{protocol}
://{host}
/3.0/projects/{projectId}
',{protocol}
://{host}
/3.0/projects/{projectId}
/queries'{protocol}
://{host}
/3.0/projects/{projectId}
/datasets'Non-matching strings will be appended to the base
resource, like so:
const url = client.url('/3.0/projects');
// Returns https://api.keen.io/3.0/projects
You can also pass in an object to append a serialized query string to the result, like so:
const url = client.url('events', { api_key: 'YOUR_API_KEY' });
// Returns https://api.keen.io/3.0/projects/PROJECT_ID/events?api_key=YOUR_API_KEY
Resources can be returned or added with the client.resources()
method, like so:
client.resources()
// Returns client.config.resources object
client.resources({
'new': '{protocol}://analytics.mydomain.com/my-custom-endpoint/{projectId}'
});
client.url('new');
// Returns 'https://analytics.mydomain.com/my-custom-endpoint/PROJECT_ID'
This is an open source project and we love involvement from the community! Hit us up with pull requests and issues.
Learn more about contributing to this project.
Need a hand with something? Shoot us an email at team@keen.io. We're always happy to help, or just hear what you're building! Here are a few other resources worth checking out:
FAQs
A JavaScript client for Keen.IO
We found that keen-analysis demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.
Security News
ENISA’s 2024 report highlights the EU’s top cybersecurity threats, including rising DDoS attacks, ransomware, supply chain vulnerabilities, and weaponized AI.